Skip to main content
POST
Context Retrieval [Cloud-only]

Authorizations

Authorization
string
header
required

API key issued by EverOS, sent as Authorization: Bearer <api_key>.

Body

application/json
query
string
required

The question to gather evidence for. The loop keeps searching until it judges the evidence sufficient to answer it, so a full question works better than a few keywords.

Minimum string length: 1
app_id
string
default:default

Scope to search in, defaulting to "default". Must match the pair used on write.

Maximum string length: 128
project_id
string
default:default

Second half of the scope, defaulting to "default".

Maximum string length: 128
user_id
string | null

Retrieve from one user's memories, matched against the messages' sender_id. Exactly one of user_id / agent_id is required; only a user owner gets episodes back.

Required string length: 1 - 256
agent_id
string | null

Accepted, but an agent owner gets no episodes, cases or skills back from this endpoint. Exactly one of user_id / agent_id is required.

Required string length: 1 - 256
method
string
default:context

Fixed to "context" and may be omitted. Any other value is rejected with 422: this endpoint does not switch retrieval methods, use /api/v2/memory/search for those.

Allowed value: "context"
top_k
integer
default:-1

Maximum number of episodes returned. Either -1 (the default, letting the engine decide) or a value from 1 to 100; anything else is rejected with 422.

radius
number | null

Accepted for compatibility with the search request and ignored: the loop runs its own searches.

Required range: 0 <= x <= 1
min_score
number | null

Not supported here: any value is rejected with 422. Results are ranked by rank fusion over the loop's searches, not by a similarity score, so there is no floor to apply.

Required range: 0 <= x <= 1
include_profile
boolean
default:false

Also return the user's profile alongside the hits, saving a second call. Ignored for an agent owner, whose results carry no profiles.

enable_llm_rerank
boolean
default:false

Accepted for compatibility with the search request and ignored: this endpoint returns no agent cases or skills.

filters
FilterNode · object | null

Optional filter tree — recursive AND / OR arrays mixed with the scalar conditions being matched.

Response

The episodes the loop found, in the same SearchData shape as /api/v2/memory/search.

request_id
string
required

Request trace id (peer to data)

data
SearchData · object
required

Endpoint-defined business result